<HTML><HEAD><TITLE>attach_tools(?Address, ++TimeOut, ?Goal)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">library(remote_tools)</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>attach_tools(?Address, ++TimeOut, ?Goal)</H1>
A flexible attachment of remote development tools
<DL>
<DT><EM>Address</EM></DT>
<DD>Address for the remote connection (Host/Port or variable)
</DD>
<DT><EM>TimeOut</EM></DT>
<DD>Time-out interval (int/float or the atom block)
</DD>
<DT><EM>Goal</EM></DT>
<DD>Goal to execute during connection
</DD>
</DL>
<H2>Description</H2>

   <P>Initiate the attachment of the remote development tools, providing the
   user with more control over the connection than attach_tools/0. The
   predicate will create a connection waiting for the remote development
   tools to be attached to.  It will then execute Goal and then tries to
   complete the connection by waiting at most TimeOut seconds for the
   remote development tools to connect.  If TimeOut is the atom block, then
   it will wait indefinitely.

   </P><P>Address is the Host/Port address that the remote connection will be
   made.  This can be left as a variable, so that the system can determine
   its own address, or the user can specify a specific Port. The main
   purpose for Goal is to allow the user to start out the remote
   development tools from it using Address, so that the user does not need
   to manually connect the remote development tools. Control is initially
   given back to ECLiPSe when the tools have been attached.

   </P><P>The predicate will fail or throw an exception if Goal respectively fails
   or throw an exception. It will also fail if it waits more than TimeOut
   seconds for the remote tools to connect. In these cases, the server
   socket will be properly closed.

   </P><P>attach_tools/0 can be implemented using attach_tools/3 as follows:

   <PRE>
         attach_tools :-
             attach_tools(_, block, true).
   </PRE>
   
<H3>Modules</H3>
This predicate is sensitive to its module context (tool predicate, see @/2).
<H3>Fail Conditions</H3>
   Development tools already attached, or waiting TimeOut seconds  
   for remote tools to connect, or if Goal fails
<H3>Resatisfiable</H3>
no
<H3>Exceptions</H3>
<DL>
<DT><EM>(4) instantiation fault </EM>
<DD>Goal or TimeOut are variables
<DT><EM>(5) type error </EM>
<DD>TimeOut is not an integer nor float nor atom
<DT><EM>(6) out of range </EM>
<DD>TimeOut is either too small or large or is an atom other than block
</DL>
<H2>Examples</H2>
<PRE>
    % the following will cause the remote tools to start automatically
    % if tktools can be run from a shell. It will wait 10 seconds before
    % failing and closing the server socket.
    [eclipse 2]:  attach_tools(H/P,10,
         exec(['tktools','--','-h',H,'-p',P], [], Pid)).

    H = 'cow.icparc.ic.ac.uk'
    P = 1953
    Pid = 27678
    Yes (0.04s cpu)
    [eclipse 3]:
   </PRE>
<H2>See Also</H2>
<A HREF="../../lib/remote_tools/tools-0.html">tools / 0</A>, <A HREF="../../lib/remote_tools/attach_tools-0.html">attach_tools / 0</A>
</BODY></HTML>
